<?php
namespace Goatherd\Convert;

/**
 * Abstract data converter.
 *
 * It is intended to not only provide string conversion. It might be more useful
 * to build complex conversion logic around object data like XML object trees.
 *
 * @todo concept full interface
 * @todo document methods
 */
interface IConverter
{
    const IS_EQUAL = 0;
    const IS_LESS = -1;
    const IS_GREATER = 1;

    /**
     * Full conversion interface.
     *
     * @param mixed    $data
     * @param string   $in_encoding      [=null]
     * @param string   $out_encoding     [=null]
     *
     * @return mixed   converted $data
     * @throws Goatherd\Convert.Exception
     */
    public function convert($data, $in_encoding = null, $out_encoding = null);

    /**
     * Abstract normalisation logic.
     *
     * @param mixed    $data
     * @throws Goatherd\Convert.Exception
     */
    public function normalise($data);

    /**
     *
     * @param mixed    $data1
     * @param mixed    $data2
     *
     * @return int     comparision result flag
     */
    public function compare($data1, $data2);

    /**
     * Default conversion.
     *
     * @param mixed    $data
     * @return mixed   converted $data
     * @throws Goatherd\Convert.Exception
     */
    public function __invoke($data);
}